<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="fr" lang="fr">
    <head>
        <title></title>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />        
        <link rel="stylesheet" type="text/css" href="../../css/guide.css" />        
        <script type="text/javascript">var basepath = '../../'; var lang = 'fr';</script>        
        <script type="text/javascript" src="../../js/loader.js"></script>        
    </head>
    <body>     
        <h1>Date</h1>
        <p>
           La classe Date permet de manipuler les données temporelles. 
        </p> 
        <h2>Configuration</h2>
        <p>
            Les options de configuration se trouvent dans la catégorie [general] du <a href="../installation/configuration.html">fichier de configuration</a>. 
            Elles se limitent à la définition du fuseau horaire et optionellement de la langue à utiliser pour <a href="../general/l10n/dates.html">l'affichage des dates en texte</a>.
        </p>
        <p>
            Exemple pour définir le fuseau horaire de Paris et le français comme langue :
        </p>
        <pre>
    [general]
        ; Time zone to use for date functions (Default is "UTC")
        timezone = "Europe/Paris"

        ; Default application locale (Default is "en_US")
        locale = "fr_FR"
        </pre>
        <h2>Instancier un objet Date</h2>
        <p>
            Il existe plusieurs méthodes pour instancier un objet date. 
            Le fait d'instancier un objet date permet ensuite de le manipuler mais également de le localiser si besoin.
        </p>
        <h3>now()</h3>
        <p>Instancie l'objet Date en utilisant le timestamp courant au moment de l'appel. Exemple :</p>
        <php>
            Date::now()->toTimeStamp();
        </php>
        
        <h3>fromTimeStamp()</h3>
        <p>Instancie l'objet Date à partir d'un timestamp donné. Exemple :</p>
        <php>
            Date::fromTimeStamp(strtotime('+10 days'));
            
            // Equivalent à Date::now()
            Date::fromTimeStamp(time());
        </php>
        
        <h3>fromString()</h3>
        <p>Instancie l'objet Date à partir d'un texte à la manière de strtotime. Exemple :</p>
        <php>
            Date::fromString("+10 days");
            
            // Equivalent à
            Date::fromTimeStamp(strtotime("+10 days"));
        </php>
        
        <h3>fromFormat()</h3>
        <p>Instancie l'objet par rapport à une date et un format donné. Le format peut utiliser les marqueurs suivants :</p>
        <ul>
            <li><strong>Y</strong> - Année sur quatre chiffre</li>
            <li><strong>n</strong> - Mois sans le zéro devant</li>
            <li><strong>m</strong> - Mois avec le zéro devant</li>
            <li><strong>M</strong> - Mois sous formet textuelle abrégée (en anglais)</li>
            <li><strong>j</strong> - Jour sans le zéro devant</li>
            <li><strong>d</strong> - Jour avec le zéro devant</li>
            <li><strong>G</strong> - Heure sans le zéro devant</li>
            <li><strong>H</strong> - Heure avec le zéro devant</li>
            <li><strong>i</strong> - Minute avec le zéro devant</li>
            <li><strong>s</strong> - Seconde avec le zéro devant</li>
        </ul>
        <php>
            Date::fromFormat('15/08/1977', 'd/m/Y');
            Date::fromFormat('08:30:06', 'H:i:s');
            Date::fromFormat('15/08/1977 08:30:06', 'd/m/Y H:i:s');
        </php>
        <blockquote class="info">
            Si aucune heure n'est donnée, l'objet date prendra par défaut 00:00:00. Si aucune date n'est donnée, l'objet prendra la date du jour.
        </blockquote>
        
        <h3>fromMySql()</h3>
        <p>
            Instancie l'objet date avec une date utilisant le format par défaut dans MySQL. 
            La méthode va détecter automatiquement si il s'agit d'un champ de type date, datetime ou timestamp.
        </p>

        <h2>Comparaison</h2>
        
        <p>
            Il est possible de comparer deux instance de Date avec les opérateurs de comparaison. Exemple :
        </p>
        <php>
            Date::fromString('-1 day') < Date::now() // retourne true
            Date::fromString('+1 day') < Date::now() // retourne false
        </php>
           
        <h2>Conversion</h2>
        <p>La classe Date permet de reformater et de localiser les dates instanciées.</p>
        
        <blockquote class="info">
            Les données localisées (jours de la semaine, mois, etc...) sont situés dans des fichiers json dans le dossier 
            oxygen/date/json. Par défaut PHP Oxygen est livré avec quelques fichiers qui s'étofferont au fil du temps 
            mais libre à vous d'en rajouter selon vos besoins.
        </blockquote>
        
        <blockquote class="warning">
            Les données localisées sont affichées en fonction de la langue du contexte définie par la méthode <a href="i18n.html">I18n::setLocale()</a>. 
            Dans le cas ou la méthode n'est pas appelée, c'est la langue par défaut qui sera prise en compte, <a href="../general/l10n.html">voyez la 
            rubrique localisation</a> pour plus de détails.
        </blockquote>        
        
        <h3>toFormat()</h3>
        <p>
            Permet de reformater la date en fonction du gabarit donné. 
            La méthode va également traduire les données textuelles en fonction de la langue donnée ou par défaut par la langue du contexte I18n courant.
        </p>
        <php>
            // On défini l'allemand comme langue par défaut
            i18n::setLocale('de');
            
            // Retourne "Sonntag 28 Februar 2010" car la langue du contexte est l'allemand
            Date::fromMySql('2010-02-28')->toFormat('l j F Y');
            
            // Retourne "dimanche 28 février 2010" car on a spécifié la langue
            Date::fromMySql('2010-02-28')->toFormat('l j F Y', 'fr');            
        </php>
        
        <h3>toSmartFormat()</h3>         
        <p>
            Permet de formater la date en utilisant un format prédéfini. Les formats sont les suivants :
        </p>
        <table>
            <tr><th>Format</td><th>Exemple en</td><th>Exemple fr</th><th>Exemple es</th></tr>
            <tr><td>shortDate</td><td>08/15/1977</td><td>15/08/1977</td><td>15/08/1977</td></tr>
            <tr><td>longDate</td><td>Monday, August 15, 1977</td><td>Lundi 15 Août 1977</td><td>Lunes, 15 de Agosto de 1977</td></tr>
            <tr><td>shortTime</td><td>08:30</td><td>08:30</td><td>08:30</td></tr>
            <tr><td>longTime</td><td>08:30:06</td><td>08:30:06</td><td>08:30:06</td></tr>
            <tr><td>fullDateTime</td><td>Monday, August 15, 1977 08:30:06</td><td>Lundi 15 Août 1977 08:30:06</td><td>Lunes, 15 de Agosto de 1977 08:30:06</td></tr>
            <tr><td>monthDay</td><td>August 15</td><td>15 Août</td><td>15 Agosto</td></tr>
            <tr><td>yearMonth</td><td>August, 1977</td><td>Août 1977</td><td>Agosto de 1977</td></tr>
        </table>

        <php>
            // On défini l'espagnol comme langue par défaut
            i18n::setLocale('es_ES');            
            
            // Retourne "Lunes, 15 de Agosto de 1977 08:30:06"
            Date::fromMySql('1977-08-15 08:30:06')->toSmartFormat('fullDateTime');
            
            // Retourne "Lundi 15 Août 1977 08:30:06"
            Date::fromMySql('1977-08-15 08:30:06')->toSmartFormat('fullDateTime', 'fr');
        </php>
        
        <h3>toMysql()</h3>
        <p>
            Retourne la date au format MySQL date, timestamp ou datetime. Cela peut être utile pour l'insertion de données 
            dans une base de données MySQL.
        </p>
        <php>            
            // retourne par exemple : "2011-06-14 18:29:34"
            Date::now()->toMysql();
            
            // retourne par exemple : "2011-06-14"
            Date::now()->toMysql('date');
        </php>
        
        <h3>toHttp()</h3>
        <p>
            Retourne la date au format HTTP standard. Utile par exemple pour définir une expiration de cache.
        </p>
        <php>
            // Retourne par exemple : "mon, 06 jun 2011 04:53:17"
            Date::now()->toHttp();
        </php>
        
        <h3>toDiff()</h3>
        <p>
            Retourne le temps restant ou le temps passé depuis la date au format textuel. Voici les paramètres de la méthode, aucun est oblogatoire :
        </p>
        
        <table>
            <tr><th>$argument</th><th>description</th><th>valeur acceptées</th><th>défaut</th></tr>
            <tr><td>$precision</td><td>Niveau de précision de la réponse, plus elle est élevée plus la réponse est détaillée</td><td>1 à 6</td><td>1</td></tr>
            <tr><td>$separator</td><td>Séparateur utilisé pour l'affichage des réponses</td><td>texte</td><td>"&nbsp;" (un espace)</td></tr>
            <tr><td>$futurePast</td><td>Doit on retourner "dans ..." ou "il y a...". La valeur retournée est localisée</td><td>booleen</td><td>true</td></tr>
            <tr><td>$timestamp</td><td>Un timestamp à partir duquel on veut comparer</td><td>entier</td><td>timestamp courant</td></tr>
            <tr><td>$langOrRegion</td><td>Le code de langue ou locale à utiliser</td><td>texte</td><td>locale courante</td></tr>
        </table>
        
        <php>
            // On défini le français comme langue par défaut
            i18n::setLocale('fr_FR'); 
            
            // Retourne "il y a 9 jours"
            Date::fromTimeStamp(strtotime('-1 week -2 days'))->toDiff();
            
            // Retourne "il y a 1 mois et 2 jours"
            Date::fromTimeStamp(strtotime('-1 month -2 days'))->toDiff(2, ' et ');
            
            // Retourne "dans 1 mois"
            Date::fromTimeStamp(strtotime('+1 month'))->toDiff();
            
            // Retourne "dans 27 jours, 2 heures"
            Date::fromTimeStamp(strtotime('+1 month -4 days +2 hours'))->toDiff(3, ', ');
        </php>
        
        <h3>toTimeStamp()</h3>
        <p>
            Récupère le timestamp de la date instanciée.
        </p>
        <php>
            // Retourne par exemple : 1307330325
            Date::now()->toTimeStamp();
        </php>
        
        <h2>Récupération de données</h2>
        <p>
            Les données de la date instanciée peuvent être récupérées de façon individuelle grâce à une série de récupérateurs (getters).
        </p>
        <h3>getDiff()</h3>
        <p>
            Génère un tableau contenant la différence avec la date en années, mois, jours, heures, minutes et secondes. 
            Indique aussi si la date est passée ou future. Par exemple :
        </p>
        <php>
            Date::fromFormat(date('2009-05-23 16:00:00'))->getDiff();
            
            /*
            array (
                'position' => 'past',
                'years' => 3,
                'months' => 2,
                'weeks' => 1,
                'days' => 4,
                'hours' => 1,
                'minutes' => 58,
                'seconds' => 46,
              )
            */
        </php>
        
        <h3>getDayOfWeek()</h3>
        <p>Retourne le jour de la semaine de la date instanciée au format numérique. (0 = dimanche)</p>
        
        <h3>getDaysInMonth()</h3>
        <p>Retourne le nombre de jour du mois de la date instanciée.</p>
        
        <h3>getDayOfYear()</h3>
        <p>Retourne le jour de l'année de la date instanciée.</p>
        
        <h3>isLeapYear()</h3>
        <p>Retourne si l'année de la date instanciée est bisextile.</p>
        
        <h2>Autres getters</h2>
        <p>Les getters suivants permettent de récupérer les valeurs des portions de la date instanciée.</p>
        
        <ul>
            <li><strong>getYear()</strong> : l'année de la date instanciée</li>
            <li><strong>getMonth()</strong> : le mois de la date instanciée</li>
            <li><strong>getDay()</strong> : le jour de la date instanciée</li>
            <li><strong>getHour()</strong> : l'heure de la date instanciée</li>
            <li><strong>getMinute()</strong> : la minute de la date instanciée</li>
            <li><strong>getSecond()</strong> : la seconde de la date instanciée</li>
        </ul>
        
        
    </body>            
</html>